Open topic with navigation

IDLnetOGCWCS

Superclasses | Creation | Properties | Methods | Examples | Version History

An IDLnetOGCWCS object lets you access a Web Coverage Service (WCS) server that supports the Open Geospatial Consortium (OGC) standards. The OGC is an international group working to develop standards for the exchange of geospatial content and services including specifications for web delivery of data that combines location and geospatial information.

For additional information on IDL’s WCS features, see the following sections:

• Web Coverage Service (WCS) Overview
• Supported OGC WCS Version
• Translating a URL into Property Values
• Using Callbacks with the IDLnetOGCWCS Object
• HTTP Authentication, Security and Encoding

Note: A sample IDL program included in the IDL distribution provides a generic WCS browser that lets you peruse and request coverages from a remote OGC server. See Sample WCS Browser for details.

Superclasses

None

Creation

See IDLnetOGCWCS::Init.

Properties

Objects of this class have the following properties. See IDLnetOGCWCS Properties for details on individual properties.

Methods

This class has the following methods:

• IDLnetOGCWCS::Cleanup
• IDLnetOGCWCS::DescribeCoverage
• IDLnetOGCWCS::GetCapabilities
• IDLnetOGCWCS::GetCoverage
• IDLnetOGCWCS::GetCoverageOffering
• IDLnetOGCWCS::GetCoverageOfferingBriefs
• IDLnetOGCWCS::GetProperty
• IDLnetOGCWCS::GetServiceSection
• IDLnetOGCWCS::Init
• IDLnetOGCWCS::ParseUrl
• IDLnetOGCWCS::SetProperty

Examples

See the following methods for examples:

• IDLnetOGCWCS::DescribeCoverage
• IDLnetOGCWCS::GetCapabilities
• IDLnetOGCWCS::GetCoverage
• IDLnetOGCWCS::GetCoverageOfferingBriefs
• IDLnetOGCWCS::ParseUrl

Sample WCS Browser

The IDL distribution includes a sample program that allows you to enter a working URL to an OGC server and then call GetCapabilities, DescribeCoverage and GetCoverage from within the user interface. You can modify property values and query characteristics to return the desired data. To run the browser program, enter OGC_WCS at the command line. See the browser help for more information.

Tip: You can use the example IDL OGC WCS Browser as a template for creating an application that queries a remote WCS server. This example is located in the IDL_DIR\examples\ogc\wcs directory where IDL_DIR is the directory where you have installed IDL. Running the example lets you parse a known, working URL to an OGC WCS server, and then make GetCapabilities, DescribeCoverage and GetCoverage requests. By default, returned files are written to your application user directory, a subdirectory of your home directory.

Version History

Web Coverage Service (WCS) Overview

A request for coverage data from an OGC WCS server involves three main requests: GetCapabilities, DescribeCoverage, and GetCoverage. The following describes these operations in terms of the IDLnetOGCWCS object:

• GetCapabilities — a general query that returns information about what types of requests are allowed and available. This includes service and summary information about data collections that are contained in “coverage offering briefs,” which are transmitted in an XML file that is written to disk.
• DescribeCoverage — a request that asks for detailed information about one or more specific coverages where each coverage is a data collection. The server returns details about the coverage(s) in an XML file that is written to disk.
• GetCoverage — a request for data relating to a specific coverage. The server transmits a copy of the raw data, containing values or properties of a set of geographic locations, in a file that is written to disk.

For details on how to use the IDLnetOGCWCS object properties and methods to request and receive information from an OGC server, see Making OGC WCS Server Requests. Also see Sample WCS Browser for information about the IDL OGC WCS Browser, a sample program included in the IDL distribution.

Additional OGC Web Coverage Service Resources

The Open Geospatial Consortium web site provides complete details on the Web Coverage Service protocol including the WCS specification and schema documents. You may find the following documents helpful if you need additional WCS resources. See OGC web site (www.opengeospatial.org) to search for these and other resource files.

Supported OGC WCS Version

This object supports version 1.0.0 of the OGC WCS standard. The IDLnetOGCWCS object conforms to the OGC WCS standard and is designed to communicate with OGC WCS compliant servers.

Note: Since this object is designed as an OGC WCS client, OGC WCS certification is not applicable. Compliance testing and certification is valid only for WCS servers.

Making OGC WCS Server Requests

This section outlines the steps required to query and return information from an OGC server. The goal is to return a data file containing a specific geospatial coverage as unrendered data. A coverage is gridded data that typically has a 1-, 2-, or 3-axis spatial coordinate reference system. Broadly, an information request from a WCS sever requires determining what data is available from a server (coverage offering briefs), determining what data collection (coverage offerings) from which you want to request data (a coverage), making the requests, and returning unrendered data.

Note: You can implement a callback to return information about the status of requests. See Using Callbacks with the IDLnetOGCWCS Object for details.

After you create an IDLnetOGCWCS object, you will need to complete the following steps:

1. Identify the WCS server. The easiest way to do this is to pass a working URL to the IDLnetOGCWCS::ParseUrl method, which sets the required URL_HOSTNAME and URL_PATH properties. Alternately, you can manually set properties related to the URL. See Translating a URL into Property Values for information on which URL components belong to which IDLnetOGCWCS properties.

   Note: If dealing with secure WCS servers, see HTTP Authentication, Security and Encoding for additional information.

2. Determine what information is available on the WCS server by making a GetCapabilities request. This typically returns and parses an XML file that contains brief information about the available coverages. See IDLnetOGCWCS::GetCapabilities for details. You can modify the CAPABILITIES_FILENAME property to define the location this file is stored.
3. Return the information contained in the coverage offering briefs by calling IDLnetOGCWCS::GetCoverageOfferingBriefs. You must call this method to return information for the specified coverage offering brief(s) in an IDL structure. The NAME field value of this structure is required to request additional information from an OGC server using the DescribeCoverage method, described next. If you wish, you can also call IDLnetOGCWCS::GetServiceSection to return service information from the XML file, but this is not necessary.
4. Request detailed information about one or more coverage offerings by specifying a value for the NAME keyword in the IDLnetOGCWCS::DescribeCoverage call. The server will typically return an XML file containing detailed information about the coverage(s). You can modify the DESCRIBE_COVERAGE_FILENAME property to define the location this file is stored.
5. Access the information in the XML file returned by DescribeCoverage by calling IDLnetOGCWCS::GetCoverageOffering. This returns a complex structure describing the offering details.
6. Return data from the server by calling IDLnetOGCWCS::GetCoverage with a number of parameters describing the exact data to be returned. You can modify the COVERAGE_FILENAME property to define the location this file is stored.
7. Model and render the data as defined by your application.

Translating a URL into Property Values

A valid WCS server URL is required to establish communication with an OGC WCS server. Additionally, IDLnetOGCWCS URL-related property values must be set before data can be successfully requested from a OGC WCS server. Either set the required properties manually (using SetProperty) or pass a URL to ParseURL. The IDLnetOGCWCS::ParseUrl method automatically parses a given URL and sets related property values.

Note: Regardless of how properties are set, the URL_HOSTNAME and URL_PATH properties must be set before calling the GetCapabilities, DescribeCoverage or GetCoverage methods.

The following table describes how the components of a given URL should be assigned to property values. Consider the following URL (which would typically exist on a single line):

http://my.hostname.com:8080/demo/cgi_path?customprefix&

Version=1.0.0&SERVICE=WCS&CustomMiddle&Request=GetCapabilities&

CustomSuffix

Components of this URL map to properties as follows.

The query portion of the URL passed to a WCS server (the parameter=value pairs following the ? character) always includes the following three parameters:

• Version takes its value from the WCS_VERSION property
• Service is set equal to “WCS” for the IDLnetOGCWCS object
• Request is one of “GetCapabilities” “DescribeCoverage”, or “GetCoverage” depending on the method in use

These three parameters are inserted into the URL automatically by IDL; any values specified for these parameters in the URL are ignored. They are not included when the URL_QUERY_PREFIX or URL_QUERY_SUFFIX properties are returned by the GetProperty method. Any query parameters that precede any of the three required parameters will be included in the URL_QUERY_PREFIX property by the ParseURL method; other nonrequired parameters will be included in the URL_QUERY_SUFFIX property.

Note: If not specified in the URL, property values besides URL_HOSTNAME and URL_PATH are set to default values. For example, the URL_PORT property defaults to 80 and the WCS_VERSION defaults to 1.0.0.

Using Callbacks with the IDLnetOGCWCS Object

Callbacks from the IDLnetOGCWCS object provide a way to transmit information back to the caller based on the status of a request made to a remote OGC WCS server. The value returned by the callback function is then used by the IDLnetOGCWCS object to determine whether to continue or abort the request.

The IDLnetOGCWCS object lets you define a single function (written in IDL) that will be called during a GetCapabilities, DescribeCoverage, or GetCoverage method call. If a callback function is specified via the CALLBACK_FUNCTION property, it is called in the following circumstances:

• For the IDLnetOGCWCS::GetCapabilities method, the callback function is called each time a packet is received from the OGC WCS server. If the FROM_FILE keyword is set, the callback function is called before and after the XML file is parsed.
• For the IDLnetOGCWCS::DescribeCoverage method, the callback function is called each time a packet is received from the OGC WCS server. If the FROM_FILE keyword is set, the callback function is called before and after the XML file is parsed.
• For the IDLnetOGCWCS::GetCoverage method, the callback function is called each time a packet of data is received from the OGC WCS server.

All methods invoke the callback function with an array of strings indicating status as the first parameter, an array of integers containing progress information as the second parameter, and with the value (if any) specified by the CALLBACK_DATA property as the third parameter. A callback function returns a value of type Int.

Cancelling a Request

The return value of the callback function should be an integer zero or one. If the return value is zero, a cancel message will be sent to the remote node. If the return value is one, the operation will continue.

Callback Routine Signature

A callback function is written in IDL and has the following signature:

Function Callback_Function_Name, StatusInfo, ProgressInfo,    CallbackData

where

• Callback_Function_Name is the name of the callback function. This value is specified as the value of the CALLBACK_FUNCTION property.
• StatusInfo is an array of strings that contain status information about the operation. The status strings are provided for information and human inspection rather than for programmatic processing; the exact strings included in the array will depend on numerous factors including the status of the operation and the type of OGC WCS server.
• ProgressInfo is an array of five 64-bit long integers that contain progress information for the transfer:
• ProgressInfo[0] – Contains 1 (one) when the ProgressInfo array contains valid data, or 0 (zero) when the array does not contain valid data.
• ProgressInfo[1] – Contains the total number of bytes to be downloaded. This array element will contain 0 (zero) when the transfer encoding is “chunked.”
• ProgressInfo[2] – Contains the number of bytes that have been downloaded during the current transfer.
• ProgressInfo[3] – Contains the total number of bytes to be uploaded.
• ProgressInfo[4] – Contains the number of bytes that have been uploaded during the current transfer.
• CallbackData is the data specified via the CALLBACK_DATA property. The value of this property is passed to the callback function unmodified. If the CALLBACK_DATA property is unspecified, an integer zero is passed to the callback function as the value of this parameter.

The CallbackData parameter is useful for passing static information, such as the widget ID of a widget where the status information is displayed, from the IDLnetOGCWCS object to the callback routine.

For a simple example of using a callback to return additional status information, see IDLnetOGCWCS::GetCapabilities. The StatusInfo details are printed to the Output window.

HTTP Authentication, Security and Encoding

The following sections describe the IDLnetOGCWCS object’s support of HTTP protocols including:

• HTTP Authentication
• HTTP Security
• HTTP Encoding

HTTP Authentication

The IDLnetOGCWCS object supports the following HTTP authentication modes for WCS and proxy servers:

• Disabled—no authentication
• Basic—plain text transmission of username and password
• Digest—encrypted transmission of username and password

By default, AUTHENTICATION and PROXY_AUTHENTICATION properties are set to “Basic and Digest” option, meaning that either basic or digest authentication are supported. However, for this setting to be honored, the corresponding username and password properties must also be set:

• For authentication on an OGC server, set USERNAME and PASSWORD properties
• For authentication on a proxy server, set PROXY_USERNAME and PROXY_PASSWORD properties

HTTP Security

The IDLnetOGCWCS object also supports HTTPS through the implementation of Secure Socket Layer (SSL). With SSL encryption, all requests and responses are encrypted. When the URL_SCHEME property is set to “https”, use the SSL_CERTIFICATE_FILE , SSL_VERIFY_HOST , and SSL_VERIFY_PEER properties to define security-related parameters.

Note: If you receive a PRNG (Pseudo Random Number Generator) error when attempting to use HTTPS on UNIX, you need to install either dev/random or dev/urandom in order to generate secure keys.

HTTP Encoding

The IDLnetOGCWCS object supports compressed and encoded responses from a remote OGC WCS server. Supported encoding formats are:

• DEFLATE
• GZIP

See the ENCODE property for details.